[release/13.4] Update Foundry hosted agent builder APIs#17669
Merged
Conversation
Consolidate AsHostedAgent usage, update Foundry icons and command rendering, and refresh playgrounds, samples, and tests. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Conditionally require/provision Foundry project ACR only for hosted-agent publish or explicit registry override, add regression tests for run/publish paths, and align PromptAgent Send Message icon with ChatSparkle. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Avoid allocating a fresh JsonSerializerOptions per Send Message command invocation, which also defeats JsonSerializer's per-options metadata cache. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
- AsHostedAgent(project, HostedAgentOptions?) is now the polyglot-exported overload
- Action<HostedAgentConfiguration> overload kept as .NET-only for advanced use
- HostedAgentOptions exposes Description, Cpu, Memory, Metadata, EnvironmentVariables
- Polyglot users now get .asHostedAgent(project, { ... }) instead of
.asHostedAgent({ project, configure: async cfg => ... })
- Updated TypeScript, Go, and Java polyglot apphost fixtures to new shape
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
HostedAgentOptions exists only to give polyglot SDK generators a clean options-bag shape. .NET callers should keep using the richer Action<HostedAgentConfiguration> overload, so both the DTO and the overload that takes it are now internal. To avoid C# overload ambiguity between '.AsHostedAgent(project)' (which should bind to the public Action overload) and the internal options overload, the internal method is renamed to AsHostedAgentForExport. The polyglot-facing name stays as 'asHostedAgent' via [AspireExport(MethodName)]. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Remove <remarks> blocks from HostedAgentOptions and AsHostedAgentForExport
that were flowing into the generated TypeScript/Go/Java SDK JSDoc and
including C#-only implementation notes plus broken <see cref> renderings
(e.g. \`AsHostedAgent\`\`1). The polyglot codegen concatenates
<summary>+<remarks>, so any C#-implementation chatter pollutes the
generated SDK docs. Replace with plain // source comments that stay in C#.
Also fix the TypeScript polyglot fixture to match the actual generated
signature: when an extension method takes a single optional DTO parameter,
the codegen wraps it in an options bag, so the call shape is
asHostedAgent(project, { options: { ... } }) — not the flat
asHostedAgent(project, { ... }) shape.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Mark HostedAgentOptions as an ATS DTO so polyglot SDK generation treats it as a JSON value object instead of a live exported handle. Update the TypeScript validation fixture to use the generated flat options shape. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Update Go and Java Foundry polyglot AppHosts to match the generated HostedAgentOptions DTO and AsHostedAgent optional-parameter shapes. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Use Double literals for hosted agent CPU and memory options so the generated Java DTO setters compile.\n\nCo-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Regenerate the Foundry ATS and API baselines so the release branch backport exposes the hosted-agent options export and drops the stale withComputeEnvironmentExecutable surface. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
🚀 Dogfood this PR with:
curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17669Or
iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17669" |
Contributor
There was a problem hiding this comment.
Pull request overview
Backport to release/13.4 of the Foundry hosted-agent API updates in Aspire.Hosting.Foundry, moving to a clearer project-first AsHostedAgent API shape for polyglot SDKs and adjusting deployment behavior so local run mode no longer creates a default Azure Container Registry (ACR) resource.
Changes:
- Replaces the polyglot-facing
WithComputeEnvironmentusage withAsHostedAgentacross C#/TS/Python/Go/Java fixtures and tests, including a typedHostedAgentOptionsDTO for polyglot configuration. - Updates Foundry project provisioning logic to only create/provision the default ACR when needed (publish/deploy / hosted-agent scenarios), and updates Azure Bicep snapshots accordingly.
- Updates Prompt Agent and Hosted Agent dashboard command/icon behavior and adds/adjusts tests to validate the new behavior.
Show a summary per file
| File | Description |
|---|---|
| tests/PolyglotAppHosts/Aspire.Hosting.Foundry/TypeScript/apphost.mts | Updates TS fixture to call asHostedAgent(project, options) with DTO-style options. |
| tests/PolyglotAppHosts/Aspire.Hosting.Foundry/Python/apphost.py | Updates Python fixture to use as_hosted_agent(project=...). |
| tests/PolyglotAppHosts/Aspire.Hosting.Foundry/Java/AppHost.java | Updates Java fixture to construct/pass HostedAgentOptions and call asHostedAgent(...). |
| tests/PolyglotAppHosts/Aspire.Hosting.Foundry/Go/apphost.go | Updates Go fixture to call AsHostedAgent(...) with options object. |
| tests/Aspire.Hosting.Foundry.Tests/PromptAgentTests.cs | Adds test coverage for the Prompt Agent “Send Message” command annotation configuration. |
| tests/Aspire.Hosting.Foundry.Tests/ProjectResourceTests.cs | Updates tests for “no default ACR in run mode” and validates default ACR removal when no hosted agents exist. |
| tests/Aspire.Hosting.Foundry.Tests/HostedAgentExtensionTests.cs | Updates hosted-agent tests to AsHostedAgent and adds coverage for export options + run-mode behaviors. |
| tests/Aspire.Hosting.Azure.Tests/Snapshots/FoundryExtensionsTests.AddProject_GeneratesEndpointFromParentFoundryApiEndpoint.verified.bicep | Updates snapshot to reflect removal of ACR resources/outputs when not required. |
| tests/Aspire.Hosting.Azure.Tests/FoundryExtensionsTests.cs | Updates Azure Foundry tests to the new hosted-agent API and run-mode ACR behavior. |
| tests/Aspire.Hosting.Azure.Tests/AzureDeployerTests.cs | Updates deploy test to use AsHostedAgent(foundryProject). |
| tests/Aspire.Deployment.EndToEnd.Tests/FoundryHostedAgentDeploymentTests.cs | Updates end-to-end deployment scenario to the new AsHostedAgent(...) API. |
| src/Aspire.Hosting.Foundry/README.md | Updates docs sample to use AsHostedAgent(project). |
| src/Aspire.Hosting.Foundry/PromptAgent/PromptAgentBuilderExtensions.cs | Adjusts Prompt Agent resource/command icon configuration. |
| src/Aspire.Hosting.Foundry/Project/ProjectResource.cs | Adds an annotation used to determine whether default ACR provisioning is required, and removes default registry when not needed. |
| src/Aspire.Hosting.Foundry/Project/ProjectBuilderExtension.cs | Creates default ACR only in publish mode; provisions ACR dependencies only when required/overridden. |
| src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentOptions.cs | Introduces internal DTO used for polyglot configuration (subset of HostedAgentConfiguration). |
| src/Aspire.Hosting.Foundry/HostedAgent/HostedAgentBuilderExtension.cs | Implements the project-first hosted-agent API (AsHostedAgent) and improves run-mode dashboard command result handling. |
| src/Aspire.Hosting.Foundry/FoundryExtensions.cs | Adds resource icons for Foundry resources/deployments (dashboard UX). |
| src/Aspire.Hosting.Foundry/api/Aspire.Hosting.Foundry.cs | Updates generated public API surface to reflect the new hosted-agent API shape and other generated deltas. |
| src/Aspire.Hosting.Foundry/api/Aspire.Hosting.Foundry.ats.txt | Updates ATS surface to include HostedAgentOptions and the new exported hosted-agent entrypoint. |
| playground/FoundryAgents/FoundryAgents.AppHost/AppHost.cs | Updates playground AppHost to use AsHostedAgent(project). |
| playground/FoundryAgentEnterprise/FoundryAgentEnterprise.AppHost/AppHost.cs | Updates enterprise playground AppHost to use the new hosted-agent API and removes redundant references. |
Copilot's findings
- Files reviewed: 22/22 changed files
- Comments generated: 2
Comment on lines
27
to
31
| /// <remarks> | ||
| /// In run mode, this configures the resource with hosted agent endpoints, health checks, | ||
| /// and OpenTelemetry settings. In publish mode, the resource is deployed as a hosted agent | ||
| /// in Microsoft Foundry. | ||
| /// This method applies in run mode. It configures the resource with the hosted agent responses endpoint, | ||
| /// a dashboard command for sending messages to the agent, and OpenTelemetry environment variables expected | ||
| /// by the Microsoft Foundry agent server SDK. | ||
| /// </remarks> |
| .AsHostedAgent(project); | ||
| ``` | ||
|
|
||
| In run mode, the agent runs locally with health check endpoints and OpenTelemetry instrumentation. In publish mode, the agent is deployed as a hosted agent in Microsoft Foundry. |
sebastienros
approved these changes
May 29, 2026
Contributor
|
❓ CLI E2E Tests unknown — 108 passed, 0 failed, 2 unknown (commit View all recordings
📹 Recordings uploaded automatically from CI run #26649968221 |
aspire-repo-bot Bot
added a commit
to microsoft/aspire.dev
that referenced
this pull request
May 29, 2026
…Agent Documents the API rename from WithComputeEnvironment/PublishAsHostedAgent to AsHostedAgent introduced in microsoft/aspire#17669. Updates all code examples, section headings, and prose in the Azure AI Foundry hosting integration docs to use the new AsHostedAgent method. Also clarifies that the default Azure Container Registry is only created in publish mode, not local run mode. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Contributor
|
Pull request created: #1130
|
This was referenced Jun 4, 2026
Merged
This was referenced Jun 4, 2026
renebentes
pushed a commit
to renebentes/3054
that referenced
this pull request
Jun 5, 2026
Updated [Aspire.Hosting.AppHost](https://github.com/microsoft/aspire) from 13.3.5 to 13.4.0. <details> <summary>Release notes</summary> _Sourced from [Aspire.Hosting.AppHost's releases](https://github.com/microsoft/aspire/releases)._ ## 13.4.0 # Aspire 13.4.0 Aspire 13.4 brings major improvements to Foundry hosted agents, the Aspire skills system, CLI reliability, and TypeScript AppHost stability — with cross-compute-environment deployment now working end-to-end and **TypeScript AppHost support — Aspire's polyglot story — reaching general availability (GA)**. ## Highlights - 🎉 **TypeScript AppHost is now GA** — First introduced as a preview in an earlier version of Aspire, the TypeScript AppHost — Aspire's polyglot story — has reached the quality bar for general availability and is now officially supported for production use alongside C#. As part of GA, the experimental markers on the Azure TypeScript AppHost (ATS) APIs have been removed and the ATS surface area is stable for 13.4. - 🤖 **Foundry hosted agents** — Protocol selection (`responses` / `invocations`) is now configurable from both C# and TypeScript AppHosts. Cross-compute-environment deployments (e.g., a Foundry hosted agent + an AKS consumer) now wire up correctly: endpoint resolution and the required **Azure AI User** RBAC role assignment on the Foundry account are generated automatically — no manual `az role assignment create` steps needed. - 🛠️ **Aspire skills catalog from bundle** — `aspire agent init` now drives its installable skill catalog from the bundle manifest, surfacing all six bundled skills (previously only three were visible). An embedded snapshot means the full catalog is available even in airgapped / disconnected environments. - 🔧 **CLI reliability** — Multiple CLI fixes: implicit-channel discovery restored, `aspire stop` no longer falsely reports failure on Unix, `aspire ps` no longer includes raw resource data (use `aspire describe` for detailed state), `aspire new` prefers the current CLI template version, friendly error for `aspire do --list-steps` without a step argument, and improved `--search` option description with documentation link. - ⌨️ **TypeScript AppHost** — Fixed a deadlock that occurred when lazy options callbacks invoked async methods; dev-localhost resource service URLs are now accepted for local development without extra configuration. - 📊 **Dashboard** — Summary log formatting improved for readability, `dotnet watch` dashboard auto-launch signal restored, and dynamic-port handling fixed for `DistributedApplicationTestingBuilder`. - ☸️ **Kubernetes** — The Helm CLI minimum version (≥ 4.2.0) is now validated before a Kubernetes deploy, giving a clear error instead of a cryptic failure. -⚠️ **`Aspire.Hosting.Blazor` ships as preview in 13.4** — A packaging issue with the Blazor gateway scripts means the package is intentionally marked preview for this release. Full stable support is targeted for 13.5. ##⚠️ Notable changes - `aspire ps` no longer includes raw resource data in its output. Use `aspire describe <resource>` to inspect detailed resource state. - Foundry hosted agent builder API shape updated — see [#17545](microsoft/aspire#17545) and [#17669](microsoft/aspire#17669) for the updated C# and TypeScript signatures. - `Aspire.Hosting.Blazor` is preview-versioned in 13.4 (`SuppressFinalPackageVersion=true`). A fix for the `addBlazorGateway` gateway script resolution error in TypeScript AppHosts is tracked in [#17685](microsoft/aspire#17685). ## 📖 Learn more For the full details on everything in this release, check out the [What's new in Aspire 13.4](https://aspire.dev/whats-new/aspire-13-4/) documentation. Thank you to all the community contributors who helped make Aspire 13.4 possible! 💜 --- *Full Changelog: microsoft/aspire@v13.3.5...v13.4.0* *Full commit: [becb48e2d61099e35ae336d527d3875e928d6594](microsoft/aspire@becb48e2d61099e35ae336d527d3875e928d6594)* > Generated by [Generate release notes for a new stable Aspire release](https://github.com/microsoft/aspire/actions/runs/26779980139/agentic_workflow) · ● 6.5M <!-- gh-aw-agentic-workflow: Generate release notes for a new stable Aspire release, engine: copilot, version: 1.0.40, model: claude-sonnet-4.6, id: 26779980139, workflow_id: release-notes-generate, run: https://github.com/microsoft/aspire/actions/runs/26779980139 --> Commits viewable in [compare view](microsoft/aspire@v13.3.5...v13.4.0). </details> [](https://docs.github.com/en/github/managing-security-vulnerabilities/about-dependabot-security-updates#about-compatibility-scores) Dependabot will resolve any conflicts with this PR as long as you don't alter it yourself. You can also trigger a rebase manually by commenting `@dependabot rebase`. [//]: # (dependabot-automerge-start) [//]: # (dependabot-automerge-end) --- <details> <summary>Dependabot commands and options</summary> <br /> You can trigger Dependabot actions by commenting on this PR: - `@dependabot rebase` will rebase this PR - `@dependabot recreate` will recreate this PR, overwriting any edits that have been made to it - `@dependabot show <dependency name> ignore conditions` will show all of the ignore conditions of the specified dependency - `@dependabot ignore this major version` will close this PR and stop Dependabot creating any more for this major version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this minor version` will close this PR and stop Dependabot creating any more for this minor version (unless you reopen the PR or upgrade to it yourself) - `@dependabot ignore this dependency` will close this PR and stop Dependabot creating any more for this dependency (unless you reopen the PR or upgrade to it yourself) </details> Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
This was referenced Jun 5, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Backport of #17545 to release/13.4
/cc @tommasodotNET
Customer Impact
Customers using Aspire Foundry hosted agents get the updated project-first API and correct hosted-agent deployment configuration behavior. Local run mode no longer creates an unnecessary default Azure Container Registry resource.
Testing
Aspire.Hosting.Foundry.Tests: 92/92 passing on the release/13.4 backport branch.Risk
Low. The changes are localized to
Aspire.Hosting.Foundryhosted-agent/project APIs and generated polyglot/API baselines, but they do affect public/generated API surface.Regression?
No.